Add draft docs mechanism (VITE_SHOW_DRAFTS) - #2637
Conversation
…in their frontmatter are hidden from the nav and return 404 when accessed directly unless VITE_SHOW_DRAFTS=true is set. In preview mode, draft nav items render in warning amber and draft pages show a callout banner.
This comment has been minimized.
This comment has been minimized.
|
Here's a visual recap of what changed: Open the full interactive recap |
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
![builder-io-integration[bot]](https://avatars.githubusercontent.com/in/353721?s=60&v=4){kind=small}
There was a problem hiding this comment.
Builder reviewed your changes and found 2 potential issues 🟡
Review Details
Code Review Summary
PR #2637 adds a preview flag for draft docs, gates default and localized document loaders, filters configured navigation entries, and adds warning styling plus a Draft banner. The route-level gating and preview presentation are straightforward, and the localized/default implementations are kept consistent.
Risk assessment: Standard — this changes public document visibility and generated discovery surfaces, in addition to UI behavior.
Key Findings
🟡 MEDIUM — Frontmatter drafts are not connected to sidebar metadata
The new filter only checks NavItemConfig.draft, but the navigation tree is static and no code derives that field from the parsed DocEntry frontmatter. A page marked draft: true therefore remains in the sidebar when drafts are disabled, where clicking it leads to a 404.
🟡 MEDIUM — Drafts remain exposed through generated Markdown/discovery assets
The loader gate protects the React route only. The docs Vite agent-web build still enumerates every Markdown source and emits draft Markdown twins, sitemap entries, and LLM entries, allowing draft content to be fetched/indexed despite the page URL returning 404.
The warning banner and amber styling are clear, and both localized and default routes apply the intended loader check.
🧪 Browser testing: Attempted after review; executor browser tools were unavailable, so HTTP/HTML fallback checks were used where possible.
| t: Translate, | ||
| ): NavItem { | ||
| ): NavItem | null { | ||
| if (config.draft && !SHOW_DRAFTS) return null; |
There was a problem hiding this comment.
🟡 Nav filtering never reads draft frontmatter
toNavItem filters only the static NavItemConfig.draft field, but this tree is not populated from the DocEntry frontmatter parsed in docs-content.ts. As a result, an existing page marked draft: true remains visible in the sidebar with drafts disabled, then navigates to the new 404 route; derive or synchronize draft status from the document metadata.
Additional Info
Confirmed by independent code-review agent and source inspection: NAV_SECTION_CONFIG contains no draft entries or metadata bridge.
| if (!doc) { | ||
| throw new Response("Not Found", { status: 404 }); | ||
| } | ||
| if (doc.draft && import.meta.env.VITE_SHOW_DRAFTS !== "true") { |
There was a problem hiding this comment.
🟡 Draft content remains exposed through generated Markdown assets
This check protects only the React document route. The docs Vite agent-web build still enumerates all source documents, including drafts, and emits their Markdown twins plus sitemap/LLM discovery entries, so /docs/<draft>.md can expose the full draft even when /docs/<draft> returns 404. Apply the same draft filter to the agent-web page generation unless previews are explicitly enabled.
Additional Info
Confirmed by independent code-review agent and inspection of packages/docs/app/vite-sitemap-plugin.ts, which parses every docs source without checking draft metadata.
2 participants
Pages with
draft: truein their frontmatter are hidden from the nav and return 404 when accessed directly unless VITE_SHOW_DRAFTS=true is set. In preview mode, draft nav items render in warning amber and draft pages show a callout banner.This is useful so we can edit docs while still referring back to the existing content. I've found this useful for me and for the AI, as I can have it compare what was there to the new content being written.
If we don't like this idea though, it's fine. It's a bit of work for a somewhat minor convenience.